A software sample demonstrates the implementation of a PC Card Ethernet driver, and an Enabler and Port Scanner to register the card and network services with. The sample is targeted for PC Card Network developers other than Ethernet PC Cards - for example, TokenRing and ATM PC Cards. In addition, a technique is demonstrated how an Ethernet PC Cards can register the "port-module" property, which the default PC Card Port Scanner detects, and use as the name of the module that will support the card. This makes it possible for the PortScanner or Enabler to define the name of the network driver module to use to support the device. Finally, the sample demonstrates how to offline the port, instead of deregistering the card.
The Problem
The default PC Card Port Scanner implemented under PC Card Manager 3.0 assumes that all PC Card Networking cards, which are inserted, are Ethernet cards. This example uses an Ethernet driver sample, but demonstrates the techniques that similar cards would implement in order to have the network services correctly registered with Open Transport. The sample also demonstrates 2 techniques for being able to specify the name of the driver that will be used to support the network card. The latter example is demonstrated by performing the OTRegisterPort call as part of this example.
How The PC Card Scanner Registers the Network Port
The following is a description on how PC Card Manager 3.0 registers network cards with Open Transport and how a driver is matched to support the network functionality. PC Card Manager v3.0 is present on the Macintosh PowerBook systems, 2400, 3400, G3 and G3 Series systems.
When a PC Card is inserted, the PC Card expert executes a call to check whether the card provides network support. It performs this check by looking in the name registry for the PC Card to check the "device-type" property associated with the card. If the "device-type" property is "network", then there is a check for the "port-configured" property. The presence of the "port-configured" property tells the PC Card network scanner that the port has already been registered. Assuming that the property does not exist, then the scanner code registers the port as an Ethernet device. To register the port, the module form of the call OTPortRegister is made. The fModuleName field is determined first by looking for the "port-module" property and second by looking for the "name" property. If the name property is used, the name item is parsed beginning from the end until the ":" character is read, or the second "," character is read. For example, if the "name" property is "mycustomethernet,myEnet123,card123", then the port scanner will set the fModuleName field to "myEnet123,card123".
The PC Card network driver must be a CFM Shared Library with a file type of 'shlb'. There is no requirement for the creator type; however, many OT drivers have the creator for the shared library file set to 'otan'. In addition, the 'cfrg' resource must have the fragment name field prefixed with "OTModl$". For the example above, the fragment name would be "OTModl$myEnet123,card123".
Registering a Non-Ethernet PC Card Network Port
To register a non-Ethernet PC Card network port, you must be able to tell the default PC Card port scanner to not register the card, and second, register the card yourself. This may sound straightforward, but there's a complication due to the fact that a PC Card Enabler is executed before Open Transport is loaded. This means that the Enabler cannot make any Open Transport calls if it is loaded at startup time. Even if the Open Transport calls are weak linked to the PC Card Enabler, then once the link fails at startup time, the OT calls are still unavailable even after OT services become available since CFM will not re-arbitrate for OT services. This sample demonstrates a technique for handling this situation. In addition, the sample demonstrates a mechanism which would be a great addition to the default port scanner - that of having the enabler create the "driver-descriptor" property in the device node and setting the property with the device-descriptor information used by OT to register PCI network cards.
For supporting newly inserted cards, the algorithm is as follows.
1. The Enabler is executed and overrides the CEAddDeviceProperties entry point in the PCCardEnablerPluginDispatchTable.
2. When the CEAddDeviceProperties handler is called, create the "port-registered" property in the device node and set the initial property value to 0. Also create the "driver-descriptor" property.
3. Determine if Open Transport is active using Gestalt. Do nothing if OT is not present as this indicates that the PortScanner will be called shortly to handle port registration.
4. If OT is present, then this indicates that the enabler is handling a hot-insertion of the card. In this case, use GetSharedLibrary to find the custom port scanner.
5. Use FindSymbol to find the custom port scanner code exported by the port scanner shared library.
6. Call the port scanner code.
7. The port scanner code searches for all NameRegistry devices with a "PCCardNodeType" property with a matching value of 'pccd'.
8. For each node with a 'pccd' "PCCardNodeType" property, search for the "port-registered" property. Only code based on this enabler would register this property.
9. Check if the "port-registered" property for a value of 0. If not zero, then this port has previously been registered with Open Transport.
10. Get the "driver-descriptor" property.
10. Allocate the memory for the TPortRecord and make the OTRegisterPort call. Use the information from the "driver-descriptor" property to set the fields of the TPortRecord. Save the deviceRef as the second parameter to the OTRegisterPort call.
11. Set the "port-registered" property to 1 to indicate that this port scanner has already registered this port.
For handling re-inserted cards, the algorithm is as follows
1. Follow steps 1 - 7 above for a newly inserted card.
2. Search through the existing port records until an offline entry is found.
3. Check that the socket number of the card matches that for the offline entry.
4. Compare the driver name from the driver descriptor with that for the offline entry.
5. If the driver names are the same, then the fContext value is updated to the current deviceRef.
6. Set the "port-registered" property to 1 to indicate that this port scanner has already registered this port.
7. Restore the fPortFalgs field so that the port is not offline.
In the above scenario, it is assumed that if the driver names match, and the PC Card is in the same slot that the card was originally in, then there is a match. One could remove the socket number match criteria so if the card was originally inserted into the upper socket, then removed and reinserted in the lower socket, then the match would still happen.
To handle hot-removal of the card, the following algorithm is used.
1. Override the CEFinalizeDevice call.
2. When called, find the port scanner shared library.
3. Find the OfflinePort routine.
4. Call the OfflinePort routine, passing in the deviceRef for the node.
5. The OfflinePort routine searches through the OT Port Register for an entry with a matching deviceRef.
6. Offline the port.
Setting the Driver Name for Ethernet PC Cards
One issue faced by Ethernet PC Cards regards a way for a common driver to support multiple Ethernet PC Cards. A simple way for this to happen is to have the Enabler create a "port-module" property with the name of the driver that will support this network port. The default PC Card port scanner will first look for this property and use the name in the property to set in the fModule field of the port record. An enabler can easily create this property by overriding the CEAddDeviceProperties entry point in the PCCardEnablerPluginDispatchTable. The example demonstrates this. Note that the presence of this property does not affect the driver name since the default PC Card port scanner will detect the presence of the "port-registered" property and discontinue trying to register the Open Transport port.
Building the Code
This sample was built using the Metrowerks CodeWarrior IDE 3.2 environment, the Open Transport 2.0.1 SDK interfaces and libraries, the Universal Interfaces and Libraries v3.2, and the PC Card 3.0 libraries.
To rebuild the project, open it in CodeWarrior, change the access path as appropriate to point to the Open Transport SDK, and to the PC Card 3.0 SDK libraries folder. If you are using the Universal Interfaces and Libraries 3.2, make sure that the Interfaces provided in the PC Card 3.0 SDK, are not used.
To use this sample within your driver, you will need to define a DriverDescriptor property for the network device. This property will be similar to that which is required for a PCI Network card driver. An example of this property is provided with the Network Driver samples provided in the Open Transport SDK.
You will need to implement/modify the CEAddDeviceProperties entry point in the PCCardEnablerPluginDispatchTable to register the required Name Registry entries in the PC Card device node.
You will need to override the CEFinalizeDevice call so that when the device is removed, you can unregister the port.
Resources
For a complete description of the Port Scanner process, refer to the "OT Advanced Client Programming Guide" v1.0b1. This document is provided as part of the Open Transport SDK. Included as part of this SDK is the "DLPI Template.pdf" document, which details the use of the Mentat Ethernet Template. You can download a copy of this Software Development Kit from the Open Transport web page, as well as access other information which will be useful in understanding networking on the Macintosh. The Open Transport web page URL is as follows:
<http://developer.apple.com/macos/opentransport/>
For access to the PC Card Manager DDK, go to the Apple Developer SDK web page. The URL is as follows:
<http://developer.apple.com/sdk/>
Issues Not Addressed/Known Issues
While this example would be useful to support ATM PC Cards, the sample does not address the issue of having the ATM MiddleWare registered as part of the ATM port registration.
An important limitation of this sample is that multiple networking cards are not supported in the same manner as are their 'ndrv' counterparts. The default PC Card Port Scanner registers a port using the IsSystemRegistered bit set and uses some additional undocumented settings. As a result, Open Transport treats the "system-registered" driver differently by providing for separate global data space. For drivers registered using the sample port scanner presented in this code, the IsSystemRegistered bit is not set and so Open Transport treats the driver differently, by only allowing a single global data space for all copies of the driver. This creates a problem for drivers which are based on existing sample code in which global data is used. As such, these drivers will not support multiple network PC Cards.
Acknowledgements
This sample was written to support the Ratoc Inc. REX-5588 Ethernet PC Card. The Enabler Code was derived from the sample written by Carl Fallis at SystemSoft, Inc, and modified by Hiroko Nishimura, Ratoc Inc, to support the REX-5588 Ethernet card.
Limitations:
You may incorporate this sample code into your applications without restriction, though the sample code has been provided "AS IS" and the responsibility for its operation is 100% yours. However, what you are not permitted to do is to redistribute the source as "DSC Sample Code"
after having made changes. If you're going to re-distribute the source, we require that you make it clear in the source that the code was descended from sample code from SystemSoft, Ratoc, and Apple, but that you've made changes.
Bug Reports:
If you find any bugs, please send them to "dts@apple.com" and include "Attn: Rich Kubota" and I will try to address them.
